home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / pounce.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  10KB  |  346 lines
  1. /**
  2.  * @file pounce.h Buddy Pounce API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_POUNCE_H_
  26. #define _GAIM_POUNCE_H_
  27.  
  28. typedef struct _GaimPounce GaimPounce;
  29.  
  30. #include <glib.h>
  31. #include "account.h"
  32.  
  33. /**
  34.  * Events that trigger buddy pounces.
  35.  */
  36. typedef enum
  37. {
  38.     GAIM_POUNCE_NONE           = 0x00, /**< No events.                    */
  39.     GAIM_POUNCE_SIGNON         = 0x01, /**< The buddy signed on.          */
  40.     GAIM_POUNCE_SIGNOFF        = 0x02, /**< The buddy signed off.         */
  41.     GAIM_POUNCE_AWAY           = 0x04, /**< The buddy went away.          */
  42.     GAIM_POUNCE_AWAY_RETURN    = 0x08, /**< The buddy returned from away. */
  43.     GAIM_POUNCE_IDLE           = 0x10, /**< The buddy became idle.        */
  44.     GAIM_POUNCE_IDLE_RETURN    = 0x20, /**< The buddy is no longer idle.  */
  45.     GAIM_POUNCE_TYPING         = 0x40, /**< The buddy started typing.     */
  46.     GAIM_POUNCE_TYPING_STOPPED = 0x80  /**< The buddy stopped typing.     */
  47.  
  48. } GaimPounceEvent;
  49.  
  50. /** A pounce callback. */
  51. typedef void (*GaimPounceCb)(GaimPounce *, GaimPounceEvent, void *);
  52.  
  53. /**
  54.  * A buddy pounce structure.
  55.  *
  56.  * Buddy pounces are actions triggered by a buddy-related event. For
  57.  * example, a sound can be played or an IM window opened when a buddy
  58.  * signs on or returns from away. Such responses are handled in the
  59.  * UI. The events themselves are done in the core.
  60.  */
  61. struct _GaimPounce
  62. {
  63.     char *ui_type;                /**< The type of UI.            */
  64.  
  65.     GaimPounceEvent events;       /**< The event(s) to pounce on. */
  66.     GaimAccount *pouncer;         /**< The user who is pouncing.  */
  67.  
  68.     char *pouncee;                /**< The buddy to pounce on.    */
  69.  
  70.     GHashTable *actions;          /**< The registered actions.    */
  71.  
  72.     gboolean save;                /**< Whether or not the pounce should
  73.                                        be saved after activation. */
  74.     void *data;                   /**< Pounce-specific data.      */
  75. };
  76.  
  77. #ifdef __cplusplus
  78. extern "C" {
  79. #endif
  80.  
  81. /**************************************************************************/
  82. /** @name Buddy Pounce API                                                */
  83. /**************************************************************************/
  84. /*@{*/
  85.  
  86. /**
  87.  * Creates a new buddy pounce.
  88.  *
  89.  * @param ui_type The type of UI the pounce is for.
  90.  * @param pouncer The account that will pounce.
  91.  * @param pouncee The buddy to pounce on.
  92.  * @param event   The event(s) to pounce on.
  93.  *
  94.  * @return The new buddy pounce structure.
  95.  */
  96. GaimPounce *gaim_pounce_new(const char *ui_type, GaimAccount *pouncer,
  97.                             const char *pouncee, GaimPounceEvent event);
  98.  
  99. /**
  100.  * Destroys a buddy pounce.
  101.  *
  102.  * @param pounce The buddy pounce.
  103.  */
  104. void gaim_pounce_destroy(GaimPounce *pounce);
  105.  
  106. /**
  107.  * Destroys all buddy pounces for the account
  108.  *
  109.  * @param account The account to remove all pounces from.
  110.  */
  111. void gaim_pounce_destroy_all_by_account(GaimAccount *account);
  112.  
  113. /**
  114.  * Sets the events a pounce should watch for.
  115.  *
  116.  * @param pounce The buddy pounce.
  117.  * @param events The events to watch for.
  118.  */
  119. void gaim_pounce_set_events(GaimPounce *pounce, GaimPounceEvent events);
  120.  
  121. /**
  122.  * Sets the account that will do the pouncing.
  123.  *
  124.  * @param pounce  The buddy pounce.
  125.  * @param pouncer The account that will pounce.
  126.  */
  127. void gaim_pounce_set_pouncer(GaimPounce *pounce, GaimAccount *pouncer);
  128.  
  129. /**
  130.  * Sets the buddy a pounce should pounce on.
  131.  *
  132.  * @param pounce  The buddy pounce.
  133.  * @param pouncee The buddy to pounce on.
  134.  */
  135. void gaim_pounce_set_pouncee(GaimPounce *pounce, const char *pouncee);
  136.  
  137. /**
  138.  * Sets whether or not the pounce should be saved after execution.
  139.  *
  140.  * @param pounce The buddy pounce.
  141.  * @param save   @c TRUE if the pounce should be saved, or @c FALSE otherwise.
  142.  */
  143. void gaim_pounce_set_save(GaimPounce *pounce, gboolean save);
  144.  
  145. /**
  146.  * Registers an action type for the pounce.
  147.  *
  148.  * @param pounce The buddy pounce.
  149.  * @param name   The action name.
  150.  */
  151. void gaim_pounce_action_register(GaimPounce *pounce, const char *name);
  152.  
  153. /**
  154.  * Enables or disables an action for a pounce.
  155.  *
  156.  * @param pounce  The buddy pounce.
  157.  * @param action  The name of the action.
  158.  * @param enabled The enabled state.
  159.  */
  160. void gaim_pounce_action_set_enabled(GaimPounce *pounce, const char *action,
  161.                                     gboolean enabled);
  162.  
  163. /**
  164.  * Sets a value for an attribute in an action.
  165.  *
  166.  * If @a value is @c NULL, the value will be unset.
  167.  *
  168.  * @param pounce The buddy pounce.
  169.  * @param action The action name.
  170.  * @param attr   The attribute name.
  171.  * @param value  The value.
  172.  */
  173. void gaim_pounce_action_set_attribute(GaimPounce *pounce, const char *action,
  174.                                       const char *attr, const char *value);
  175.  
  176. /**
  177.  * Sets the pounce-specific data.
  178.  *
  179.  * @param pounce The buddy pounce.
  180.  * @param data   Data specific to the pounce.
  181.  */
  182. void gaim_pounce_set_data(GaimPounce *pounce, void *data);
  183.  
  184. /**
  185.  * Returns the events a pounce should watch for.
  186.  *
  187.  * @param pounce The buddy pounce.
  188.  *
  189.  * @return The events the pounce is watching for.
  190.  */
  191. GaimPounceEvent gaim_pounce_get_events(const GaimPounce *pounce);
  192.  
  193. /**
  194.  * Returns the account that will do the pouncing.
  195.  *
  196.  * @param pounce The buddy pounce.
  197.  *
  198.  * @return The account that will pounce.
  199.  */
  200. GaimAccount *gaim_pounce_get_pouncer(const GaimPounce *pounce);
  201.  
  202. /**
  203.  * Returns the buddy a pounce should pounce on.
  204.  *
  205.  * @param pounce The buddy pounce.
  206.  *
  207.  * @return The buddy to pounce on.
  208.  */
  209. const char *gaim_pounce_get_pouncee(const GaimPounce *pounce);
  210.  
  211. /**
  212.  * Returns whether or not the pounce should save after execution.
  213.  *
  214.  * @param pounce The buddy pounce.
  215.  *
  216.  * @return @c TRUE if the pounce should be saved after execution, or
  217.  *         @c FALSE otherwise.
  218.  */
  219. gboolean gaim_pounce_get_save(const GaimPounce *pounce);
  220.  
  221. /**
  222.  * Returns whether or not an action is enabled.
  223.  *
  224.  * @param pounce The buddy pounce.
  225.  * @param action The action name.
  226.  *
  227.  * @return @c TRUE if the action is enabled, or @c FALSE otherwise.
  228.  */
  229. gboolean gaim_pounce_action_is_enabled(const GaimPounce *pounce,
  230.                                        const char *action);
  231.  
  232. /**
  233.  * Returns the value for an attribute in an action.
  234.  *
  235.  * @param pounce The buddy pounce.
  236.  * @param action The action name.
  237.  * @param attr   The attribute name.
  238.  *
  239.  * @return The attribute value, if it exists, or @c NULL.
  240.  */
  241. const char *gaim_pounce_action_get_attribute(const GaimPounce *pounce,
  242.                                              const char *action,
  243.                                              const char *attr);
  244.  
  245. /**
  246.  * Returns the pounce-specific data.
  247.  *
  248.  * @param pounce The buddy pounce.
  249.  *
  250.  * @return The data specific to a buddy pounce.
  251.  */
  252. void *gaim_pounce_get_data(const GaimPounce *pounce);
  253.  
  254. /**
  255.  * Executes a pounce with the specified pouncer, pouncee, and event type.
  256.  *
  257.  * @param pouncer The account that will do the pouncing.
  258.  * @param pouncee The buddy that is being pounced.
  259.  * @param events  The events that triggered the pounce.
  260.  */
  261. void gaim_pounce_execute(const GaimAccount *pouncer, const char *pouncee,
  262.                          GaimPounceEvent events);
  263.  
  264. /*@}*/
  265.  
  266. /**************************************************************************/
  267. /** @name Buddy Pounce Subsystem API                                      */
  268. /**************************************************************************/
  269. /*@{*/
  270.  
  271. /**
  272.  * Finds a pounce with the specified event(s) and buddy.
  273.  *
  274.  * @param pouncer The account to match against.
  275.  * @param pouncee The buddy to match against.
  276.  * @param events  The event(s) to match against.
  277.  *
  278.  * @return The pounce if found, or @c NULL otherwise.
  279.  */
  280. GaimPounce *gaim_find_pounce(const GaimAccount *pouncer,
  281.                              const char *pouncee, GaimPounceEvent events);
  282.  
  283.  
  284. /**
  285.  * Loads the pounces.
  286.  *
  287.  * @return @c TRUE if the pounces could be loaded.
  288.  */
  289. gboolean gaim_pounces_load(void);
  290.  
  291. /**
  292.  * Force an immediate write of pounces.
  293.  */
  294. void gaim_pounces_sync(void);
  295.  
  296. /**
  297.  * Registers a pounce handler for a UI.
  298.  *
  299.  * @param ui          The UI name.
  300.  * @param cb          The callback function.
  301.  * @param new_pounce  The function called when a pounce is created.
  302.  * @param free_pounce The function called when a pounce is freed.
  303.  */
  304. void gaim_pounces_register_handler(const char *ui, GaimPounceCb cb,
  305.                                    void (*new_pounce)(GaimPounce *pounce),
  306.                                    void (*free_pounce)(GaimPounce *pounce));
  307.  
  308. /**
  309.  * Unregisters a pounce handle for a UI.
  310.  *
  311.  * @param ui The UI name.
  312.  */
  313. void gaim_pounces_unregister_handler(const char *ui);
  314.  
  315. /**
  316.  * Returns a list of all registered buddy pounces.
  317.  *
  318.  * @return The list of buddy pounces.
  319.  */
  320. GList *gaim_pounces_get_all(void);
  321.  
  322. /**
  323.  * Returns the buddy pounce subsystem handle.
  324.  *
  325.  * @return The subsystem handle.
  326.  */
  327. void *gaim_pounces_get_handle(void);
  328.  
  329. /**
  330.  * Initializes the pounces subsystem.
  331.  */
  332. void gaim_pounces_init(void);
  333.  
  334. /**
  335.  * Uninitializes the pounces subsystem.
  336.  */
  337. void gaim_pounces_uninit(void);
  338.  
  339. /*@}*/
  340.  
  341. #ifdef __cplusplus
  342. }
  343. #endif
  344.  
  345. #endif /* _GAIM_POUNCE_H_ */
  346.